Skip to content

feat(tokens): add comprehensive design tokens package #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
Ndacyayisenga-droid merged 2 commits into from
Dec 9, 2025
Merged

feat(tokens): add comprehensive design tokens package #45

Ndacyayisenga-droid merged 2 commits into from
Dec 9, 2025

Conversation

@IamLRBA
Copy link
Contributor

@IamLRBA IamLRBA commented Dec 8, 2025 •
edited by Ndacyayisenga-droid
Loading

Pull Request Description

Summary

This PR introduces a comprehensive design tokens package (@ode/tokens) for the ODE ecosystem, establishing a unified design system foundation as proposed in GitHub Discussion #29.

What's Included

Complete Design Token System

  • Base Tokens: Colors (brand primary/secondary, neutral, semantic), typography, spacing (4px scale), borders, shadows, motion, z-index, opacity
  • Semantic Tokens: Success, error, warning, and info color tokens
  • Component Tokens: Icon sizes, avatar sizes, logo sizes
  • Layout Tokens: Responsive breakpoints, container max-widths, grid system
  • Accessibility Tokens: WCAG contrast ratios, focus states, minimum touch target sizes

Multiple Output Formats

The package generates tokens in multiple formats for cross-platform compatibility:

  • CSS Variables (dist/css/tokens.css) - For React Web projects
  • JavaScript/TypeScript (dist/js/tokens.js + .d.ts) - For React Web with type safety
  • React Native (dist/react-native/tokens.js) - For mobile applications
  • JSON (dist/json/tokens.json) - Raw token data for other tools

Developer Experience

  • Style Dictionary Integration: Automated token generation from JSON source files
  • TypeScript Support: Full type definitions included
  • Comprehensive Documentation: 6 detailed documentation files covering all aspects
  • Well-Organized Structure: Clear categorization (base, semantic, component, layout, accessibility)

Documentation

  • README.md: Main documentation with quick start guide
  • QUICK_START.md: 5-minute getting started guide
  • DESIGN_TOKENS_SPECIFICATION.md: Complete token reference with all values
  • EXAMPLES.md: Real-world usage examples (CSS, React Web, React Native, Material UI)
  • CONTRIBUTING.md: Guide for adding and modifying tokens
  • SETUP_COMPLETE.md: Package structure overview

File Structure

packages/tokens/
├── src/tokens/              # Source token files (JSON)
│   ├── base/               # Foundation tokens (9 files)
│   ├── semantic/            # Semantic colors
│   ├── components/          # Component-specific tokens
│   ├── layout/              # Layout tokens
│   └── accessibility/      # Accessibility tokens
├── dist/                    # Generated outputs (after build)
├── config.json              # Style Dictionary configuration
├── style-dictionary.config.js
└── package.json

Token Categories

  1. Base Tokens (9 files): Colors, typography, spacing, borders, shadows, motion, z-index, opacity
  2. Semantic Tokens: Success, error, warning, info colors
  3. Component Tokens: Icons, avatars, logos
  4. Layout Tokens: Breakpoints, containers, grid
  5. Accessibility Tokens: Contrast, focus, touch targets

Design Principles

  • Accessibility First: All colors meet WCAG 2.1 AA contrast ratios
  • Consistency: Unified visual language across all platforms
  • Simplicity: Clear, predictable token names
  • Scalability: Easy to extend and maintain

Testing

  • ✅ All token JSON files validated
  • ✅ Style Dictionary configuration tested
  • ✅ Documentation cross-referenced and verified
  • ✅ No linter errors

Breaking Changes

None - This is a new package addition.

@IamLRBA
feat(tokens): add comprehensive design tokens package
eea5434 
Introduce @ode/tokens package with complete design token system for unified
ODE design system. Includes base tokens (colors, typography, spacing, borders,
shadows, motion, z-index, opacity), semantic tokens, component tokens, layout
tokens, and accessibility tokens.

Related: #29
najuna-brian
najuna-brian reviewed Dec 8, 2025
View reviewed changes
Copy link
Contributor

@najuna-brian najuna-brian left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we consider adding a test suite and CI workflow to validate tokens on PRs?

@IamLRBA
fix(tokens): fix Style Dictionary build errors
ef21868 
- Fixed fileHeader registration using registerFileHeader()
- Fixed fileHeader return type to return array of strings
- Fixed React Native shadows by splitting shadowOffset into width/height

Resolves build errors and enables successful token generation.
@IamLRBA
Copy link
Contributor Author

IamLRBA commented Dec 9, 2025

New Changes

Fixed three issues that prevented token generation and addressed PR review comments.:

  1. FileHeader registration: Changed from registerFormat() to registerFileHeader()
    to properly register the custom header function

  2. FileHeader return type: Changed customHeader function to return an array
    of strings instead of a single string, as required by Style Dictionary

  3. React Native shadow syntax: Split shadowOffset into shadowOffsetWidth and
    shadowOffsetHeight to fix invalid token reference errors. This addresses
    the @najuna-brian's concern about React Native shadow format.
    Thanks for pointing that out @najuna-brian! 😊

After these fixes, Style Dictionary successfully generates all output formats:

  • CSS variables (dist/css/tokens.css)
  • JavaScript/TypeScript (dist/js/tokens.js + .d.ts)
  • JSON (dist/json/tokens.json)
  • React Native (dist/react-native/tokens.js + .d.ts)

@Ndacyayisenga-droid Ndacyayisenga-droid merged commit fb0e59a into OpenDataEnsemble:main Dec 9, 2025
7 checks passed
@IamLRBA IamLRBA deleted the ode_design_tokens branch December 10, 2025 10:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@najuna-brian najuna-brian najuna-brian left review comments

@Ndacyayisenga-droid Ndacyayisenga-droid Ndacyayisenga-droid approved these changes

@Bahati308 Bahati308 Awaiting requested review from Bahati308

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@IamLRBA @Ndacyayisenga-droid @najuna-brian